home *** CD-ROM | disk | FTP | other *** search
/ Suzy B Software 2 / Suzy B Software CD-ROM 2 (1994).iso / bootup / boot_a2m / digivec / digivec.doc < prev    next >
Encoding:
Text File  |  1995-05-02  |  7.0 KB  |  265 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.                                  Digivec
  18.  
  19.                            Copyright (C) 1990
  20.                             By David Baggett
  21.  
  22.  
  23. --------------------------------------------------------------------------------
  24.                              User Contract
  25.  
  26. This program is FREE.  You may distribute it at will, provided you
  27.  
  28.         1) do not charge any money for it,
  29.         2) distribute it WITH the documentation, and
  30.         3) do not change the program or documentation in ANY WAY.
  31.  
  32. --------------------------------------------------------------------------------
  33.  
  34.  
  35. Introduction  
  36. ------------
  37.  
  38.       "My ST was so boring before I got Digivec!"
  39.  
  40.       "Programming just isn't the same without it."
  41.  
  42.       "I just wouldn't know what to do if someone took away my Digivec!"
  43.  
  44.  
  45.    You'll agree with these happy customers once you too try the exciting new
  46. shareware utility that's taking the ST world by storm!  It's Digivec, and
  47. once you install it on your system, you won't know how you ever lived
  48. without it.
  49.  
  50.    Got your attention?  Good.  Okay, listen up.  Digivec lets you install
  51. digitized sounds to be played when various system events occur.  Like
  52. bus errors.  Illegal instruction traps.  Or line A calls.  Even...
  53. GEM critical errors (gasp!).
  54.  
  55.  
  56. General Usage
  57. -------------
  58.  
  59.    Put digivec.prg in your AUTO folder.  Then create a file called 
  60. digivec.inf with a standard ASCII text editor and put it in the root 
  61. directory of your boot partition (e.g., if your AUTO folder is C:\AUTO\, 
  62. put digivec.inf in C:\).
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.    In digivec.inf you specify which sounds will be installed, and what events
  73. will trigger them.  Each entry starts with a sample file name, enclosed
  74. in square brackets, followed by the sample playback speed, in Hertz, 
  75. followed by a list of system vectors which will trigger the sound.  Here's 
  76. an example digivec.inf file:
  77.  
  78. [d:\usr\sounds\buserror.snd]    11000   $8 $C
  79.  
  80. This file tells Digivec to load the sample named d:\usr\sounds\buserror.snd
  81. and to play it at 11000 Hz whenever vectors 8 (hex) and C (hex) are jumped 
  82. through (in this case, any time either a bus error or address error occur).
  83.  
  84.    Increasing the number 11000 will make the sound play faster; decreasing
  85. it will make the sound play slower.
  86.  
  87.    The digivec.inf file can contain as many of these entries as you want;
  88. the only limitation is that all the samples have to fit in memory at once.
  89.  
  90.    Note that file names MUST be enclosed in square brackets.
  91.  
  92.  
  93. The Vectors
  94. -----------
  95.  
  96.    You can specify the system vectors either in hexadecimal (with leading $)
  97. or decimal (no leading $).  Interesting vectors for triggering sounds
  98. include (but are not limited to):
  99.  
  100.         Hex     Decimal         Description
  101.         ---     -------         -----------
  102.         $8       8              Bus Error
  103.         $C       12             Address Error
  104.         $10      16             Illegal Instruction
  105.         $14      20             Division by Zero
  106.         $20      32             Privilege Violation
  107.         $28      40             Line A Emulator
  108.         $2C      44             Line F Emulator
  109.  
  110.         $404     1028           Critical Error 
  111.         $408     1032           Process Termination
  112.         $476     1142           Drive read/write
  113.  
  114.    The first 5 vectors deal with failures caused (typically) by software
  115. bugs.  These are the things that cause the ST to put bombs on the 
  116. screen.  But it's so much more fun to have the ST say "Just what do
  117. you think you're doing, Dave?" when a bus error occurs.  (Especially
  118. if your name is Dave and you crash the machine a lot...)
  119.  
  120.    The Line A and Line F emulators are typically used to call system 
  121. functions. (Line A is used for drawing functions; Line F is used in a very 
  122. few programs for pulling off bizarre hacks and/or for floating point).  
  123. Triggering sounds with these is not terribly useful unless you're a 
  124. programmer-type and want to see just what a given application is up to.  
  125. (It's also neat to install a sound at Line A and then run NEOchrome!)
  126.  
  127.    GEM uses the critcal error vector when various things confuse it.  The 
  128. most common of these is trying to read or write with no disk in the drive.
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.    The process termination vector will trigger a sound whenever any program
  139. exits.  This can get extremely annoying after a while.  Trust me.  It's
  140. really fun to install this one on a machine when the owner isn't looking.
  141.  
  142.    If you miss your Atari 800, with it's "boop boop boop" disk access,
  143. you can trigger a sound with the disk read/write vector.  Another good
  144. one to surprise your friends with.
  145.  
  146.  
  147. Command Line Usage
  148. ------------------
  149.  
  150.    Digivec is only meant to be run from within the AUTO folder.  It does
  151. some "unusual" things to ensure that the sounds do not get un-installed
  152. when GEM loads.  One side effect of this is that if you run Digivec from
  153. the desktop or from a command shell, it won't do anything except take
  154. up memory, UNLESS you pass it a parameter.  It doesn't matter what the
  155. parameter is, as long as you pass one.
  156.  
  157.    To run digivec from the desktop, you'll need to rename a copy digivec.ttp.
  158. When you click on it, the desktop will ask for parameters.  Just type an x 
  159. and hit return.  Then Digivec will know it's not running from within the AUTO 
  160. folder and will work correctly. 
  161.  
  162.    To run Digivec from a command shell (e.g., GULAM), type 
  163.  
  164.         digivec x
  165.  
  166.    Note that when you run Digivec from the desktop or a command shell,
  167. it looks for digivec.inf in the current working directory.
  168.  
  169.  
  170. Technical Information
  171. ---------------------
  172.  
  173.    Digivec works by installing a new exception handler for each vector
  174. specified in digivec.inf.  Each new handler just plays the appropriate
  175. sound then jumps through the old vector.  This should not adversely affect 
  176. the system in any way, except in cases where timing is critical.  (So 
  177. don't trigger sounds with the horizontal blank interrupt!)
  178.  
  179.    Minor problems are caused by the fact that when GEM loads (after AUTO
  180. folder programs are finished), it obliterates the critical error vector and 
  181. the process termination vector and installs its own.  To get around this,
  182. Digivec waits for GEM to finish loading before it actually installs any 
  183. vectors.
  184.  
  185.  
  186. Caveats
  187. -------
  188.  
  189.    Digivec will replace any vector in the system.  It does not check to make 
  190. sure the vectors you specify are reasonable.  This means that you could 
  191. theoretically replace some vector in the system that no one else has thought 
  192. of replacing, with nifty results.  It also means you could make your ST crash 
  193. in all kinds of hideous ways.
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.    The upshot is this:  Don't put digivec.prg in your AUTO folder until 
  204. you're sure you know how to boot your system without Digivec getting run.  
  205. If you're a hard drive user, be sure you know how to bypass the hard drive, 
  206. so that if your digivec.inf is not kosher you'll still be able to use your 
  207. machine.
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.